﻿using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace OOLib
{
   /// <summary>
   /// This is a simple interface to load components by an URL into a frame environment.
   /// </summary>
   public interface IComponentLoader
   {
      /// <summary>
      /// Loads a component specified by an URL into the specified new or existing frame.
      /// </summary>
      /// <param name="url">
      /// Specifies the URL of the document to load.
      /// To create new documents, use "private:factory/scalc", "private:factory/swriter", 
      /// etc. Other special protocols (e.g. "slot:", ".uno") are not allowed and raise an ::com::sun::star::lang::IllegalArgumentException. 
      /// </param>
      /// <param name="targetFrameName">
      /// Specifies the name of the frame to view the document in.
      /// If a frame with the specified name already exists, it is used, otherwise it is created. 
      /// There exist some special targets which never can be used as real frame names: 
      /// "_blank" always creates a new frame 
      /// "_default" special UI functionality (e.g. detecting of already loaded documents, using of empty frames of creating of new top frames as fallback) 
      /// "_self", ""(!) means frame himself 
      /// "_parent" address direct parent of frame 
      /// "_top" indicates top frame of current path in tree 
      /// "_beamer" means special sub frame 
      /// </param>
      /// <param name="searchFlags">
      /// Use the values of FrameSearchFlag to specify how to find the specified TargetFrameName.
      /// Note: These flags are optional ones and will be used for non special target names only.
      /// </param>
      /// <param name="hidden">true if the Window in which the document is opend should be hidden, false otherwiese.</param>
      /// <returns>Returns the raw Com object</returns>
      object LoadComponentFromURLRaw(string url, string targetFrameName, int searchFlags, bool hidden);

      /// <summary>
      /// Loads a component specified by an URL into the specified new or existing frame.
      /// </summary>
      /// <param name="url">
      /// Specifies the URL of the document to load.
      /// To create new documents, use "private:factory/scalc", "private:factory/swriter", 
      /// etc. Other special protocols (e.g. "slot:", ".uno") are not allowed and raise an ::com::sun::star::lang::IllegalArgumentException. 
      /// </param>
      /// <param name="targetFrameName">
      /// Specifies the name of the frame to view the document in.
      /// If a frame with the specified name already exists, it is used, otherwise it is created. 
      /// There exist some special targets which never can be used as real frame names: 
      /// "_blank" always creates a new frame 
      /// "_default" special UI functionality (e.g. detecting of already loaded documents, using of empty frames of creating of new top frames as fallback) 
      /// "_self", ""(!) means frame himself 
      /// "_parent" address direct parent of frame 
      /// "_top" indicates top frame of current path in tree 
      /// "_beamer" means special sub frame 
      /// </param>
      /// <param name="searchFlags">
      /// Use the values of FrameSearchFlag to specify how to find the specified TargetFrameName.
      /// Note: These flags are optional ones and will be used for non special target names only.
      /// </param>
      /// <param name="arguments">
      /// these arguments specify component or filter specific behavior.
      /// For example, "ReadOnly" with a boolean value specifies whether the document is opened read-only. 
      /// "FilterName" specifies the component type to create and the filter to use, for example: 
      /// "Text - CSV". For more information see ::com::sun::star::document::MediaDescriptor.
      /// </param>
      /// <returns>Returns the raw Com object</returns>
      object LoadComponentFromURLRaw(string url, string targetFrameName, int searchFlags, object[] arguments);

      /// <summary>
      /// Loads a component specified by an URL into the specified new or existing frame.
      /// </summary>
      /// <param name="url">
      /// Specifies the URL of the document to load.
      /// To create new documents, use "private:factory/scalc", "private:factory/swriter", 
      /// etc. Other special protocols (e.g. "slot:", ".uno") are not allowed and raise an ::com::sun::star::lang::IllegalArgumentException. 
      /// </param>
      /// <param name="targetFrameName">
      /// Specifies the name of the frame to view the document in.
      /// If a frame with the specified name already exists, it is used, otherwise it is created. 
      /// There exist some special targets which never can be used as real frame names: 
      /// "_blank" always creates a new frame 
      /// "_default" special UI functionality (e.g. detecting of already loaded documents, using of empty frames of creating of new top frames as fallback) 
      /// "_self", ""(!) means frame himself 
      /// "_parent" address direct parent of frame 
      /// "_top" indicates top frame of current path in tree 
      /// "_beamer" means special sub frame 
      /// </param>
      /// <param name="searchFlags">
      /// Use the values of FrameSearchFlag to specify how to find the specified TargetFrameName.
      /// Note: These flags are optional ones and will be used for non special target names only.
      /// </param>
      /// <param name="hidden">true if the Window in which the document is opend should be hidden, false otherwiese.</param>
      /// <returns>
      /// Returns a ::com::sun::star::lang::XComponent for successfully loaded documents or NULL if it failed .
      /// This interface is a generic one and can be used to start further requests on loaded document or control the 
      /// lifetime of it (means dispose() it after using). The real document service behind this interface can be one of follow three ones: 
      /// ::com::sun::star::awt::XWindow for simple components Should be used for viewable components only. 
      /// It is not allowed to dispose it after use directly, because the frame containing the component is its owner. 
      /// Because the frame object is not accessible through the interface too, only an interacting user can do this by closing the frames' window. 
      /// XController for richer components Should be used for real editable components which doesn't need a model. 
      /// It is not allowed to dispose it after use directly, because the frame containing the component is its owner. 
      /// Here the object can be disposed by disposing the frame, that the XController::getFrame() method of the controller returns. 
      /// But for visible components the controller should be asked for permission by calling XController::suspend() before. 
      /// XModel for full featured components
      /// A model that in general can be shared between several view/controller pairs, does not have an explicit owner. 
      /// Every view and also the component that loaded the document may consider itself as an owner. Simply calling XComponent::dispose 
      /// on this model may cause problems, if some members of the "owner community" are currently busy working on the model. 
      /// These problems are handled by explicit closing negotiations through the interface ::com::sun::star::util::XCloseable. 
      /// Direct dispose of the model is allowed only, if this special interface doesn't exist.
      /// </returns>
      T LoadComponentFromURL<T>(string url, string targetFrameName = "_blank", FrameSearchFlag searchFlags = FrameSearchFlag.AUTO, bool hidden = false) where T : Component, new();

      /// <summary>
      /// Loads a component specified by an URL into the specified new or existing frame.
      /// </summary>
      /// <param name="url">
      /// Specifies the URL of the document to load.
      /// To create new documents, use "private:factory/scalc", "private:factory/swriter", 
      /// etc. Other special protocols (e.g. "slot:", ".uno") are not allowed and raise an ::com::sun::star::lang::IllegalArgumentException. 
      /// </param>
      /// <param name="targetFrameName">
      /// Specifies the name of the frame to view the document in.
      /// If a frame with the specified name already exists, it is used, otherwise it is created. 
      /// There exist some special targets which never can be used as real frame names: 
      /// "_blank" always creates a new frame 
      /// "_default" special UI functionality (e.g. detecting of already loaded documents, using of empty frames of creating of new top frames as fallback) 
      /// "_self", ""(!) means frame himself 
      /// "_parent" address direct parent of frame 
      /// "_top" indicates top frame of current path in tree 
      /// "_beamer" means special sub frame 
      /// </param>
      /// <param name="searchFlags">
      /// Use the values of FrameSearchFlag to specify how to find the specified TargetFrameName.
      /// Note: These flags are optional ones and will be used for non special target names only.
      /// </param>
      /// <param name="arguments">
      /// these arguments specify component or filter specific behavior.
      /// For example, "ReadOnly" with a boolean value specifies whether the document is opened read-only. 
      /// "FilterName" specifies the component type to create and the filter to use, for example: 
      /// "Text - CSV". For more information see ::com::sun::star::document::MediaDescriptor.
      /// </param>
      /// <returns>
      /// Returns a ::com::sun::star::lang::XComponent for successfully loaded documents or NULL if it failed .
      /// This interface is a generic one and can be used to start further requests on loaded document or control the 
      /// lifetime of it (means dispose() it after using). The real document service behind this interface can be one of follow three ones: 
      /// ::com::sun::star::awt::XWindow for simple components Should be used for viewable components only. 
      /// It is not allowed to dispose it after use directly, because the frame containing the component is its owner. 
      /// Because the frame object is not accessible through the interface too, only an interacting user can do this by closing the frames' window. 
      /// XController for richer components Should be used for real editable components which doesn't need a model. 
      /// It is not allowed to dispose it after use directly, because the frame containing the component is its owner. 
      /// Here the object can be disposed by disposing the frame, that the XController::getFrame() method of the controller returns. 
      /// But for visible components the controller should be asked for permission by calling XController::suspend() before. 
      /// XModel for full featured components
      /// A model that in general can be shared between several view/controller pairs, does not have an explicit owner. 
      /// Every view and also the component that loaded the document may consider itself as an owner. Simply calling XComponent::dispose 
      /// on this model may cause problems, if some members of the "owner community" are currently busy working on the model. 
      /// These problems are handled by explicit closing negotiations through the interface ::com::sun::star::util::XCloseable. 
      /// Direct dispose of the model is allowed only, if this special interface doesn't exist.
      /// </returns>
      T LoadComponentFromURLWithArgs<T>(string url, string targetFrameName = "_blank", FrameSearchFlag searchFlags = FrameSearchFlag.AUTO, object[] arguments = null) where T : Component, new();

         /// <summary>
      /// Loads a component specified by an URL into the specified new or existing frame.
      /// </summary>
      /// <param name="fileName">Specifies the file name of the document to load.</param>
      /// <param name="targetFrameName">
      /// Specifies the name of the frame to view the document in.
      /// If a frame with the specified name already exists, it is used, otherwise it is created. 
      /// There exist some special targets which never can be used as real frame names: 
      /// "_blank" always creates a new frame 
      /// "_default" special UI functionality (e.g. detecting of already loaded documents, using of empty frames of creating of new top frames as fallback) 
      /// "_self", ""(!) means frame himself 
      /// "_parent" address direct parent of frame 
      /// "_top" indicates top frame of current path in tree 
      /// "_beamer" means special sub frame 
      /// </param>
      /// <param name="searchFlags">
      /// Use the values of FrameSearchFlag to specify how to find the specified TargetFrameName.
      /// Note: These flags are optional ones and will be used for non special target names only.
      /// </param>
      /// <param name="hidden">true if the Window in which the document is opend should be hidden, false otherwiese.</param>
      /// <returns>
      /// Returns a ::com::sun::star::lang::XComponent for successfully loaded documents or NULL if it failed .
      /// This interface is a generic one and can be used to start further requests on loaded document or control the 
      /// lifetime of it (means dispose() it after using). The real document service behind this interface can be one of follow three ones: 
      /// ::com::sun::star::awt::XWindow for simple components Should be used for viewable components only. 
      /// It is not allowed to dispose it after use directly, because the frame containing the component is its owner. 
      /// Because the frame object is not accessible through the interface too, only an interacting user can do this by closing the frames' window. 
      /// XController for richer components Should be used for real editable components which doesn't need a model. 
      /// It is not allowed to dispose it after use directly, because the frame containing the component is its owner. 
      /// Here the object can be disposed by disposing the frame, that the XController::getFrame() method of the controller returns. 
      /// But for visible components the controller should be asked for permission by calling XController::suspend() before. 
      /// XModel for full featured components
      /// A model that in general can be shared between several view/controller pairs, does not have an explicit owner. 
      /// Every view and also the component that loaded the document may consider itself as an owner. Simply calling XComponent::dispose 
      /// on this model may cause problems, if some members of the "owner community" are currently busy working on the model. 
      /// These problems are handled by explicit closing negotiations through the interface ::com::sun::star::util::XCloseable. 
      /// Direct dispose of the model is allowed only, if this special interface doesn't exist.
      /// </returns>
      T LoadComponentFromFile<T>(string fileName, string targetFrameName = "_blank", FrameSearchFlag searchFlags = FrameSearchFlag.AUTO, bool hidden = false) where T : Component, new();

      /// <summary>
      /// Loads a component specified by an URL into the specified new or existing frame.
      /// </summary>
      /// <param name="fileName">Specifies the file name of the document to load.</param>
      /// <param name="targetFrameName">
      /// Specifies the name of the frame to view the document in.
      /// If a frame with the specified name already exists, it is used, otherwise it is created. 
      /// There exist some special targets which never can be used as real frame names: 
      /// "_blank" always creates a new frame 
      /// "_default" special UI functionality (e.g. detecting of already loaded documents, using of empty frames of creating of new top frames as fallback) 
      /// "_self", ""(!) means frame himself 
      /// "_parent" address direct parent of frame 
      /// "_top" indicates top frame of current path in tree 
      /// "_beamer" means special sub frame 
      /// </param>
      /// <param name="searchFlags">
      /// Use the values of FrameSearchFlag to specify how to find the specified TargetFrameName.
      /// Note: These flags are optional ones and will be used for non special target names only.
      /// </param>
      /// <param name="arguments">
      /// these arguments specify component or filter specific behavior.
      /// For example, "ReadOnly" with a boolean value specifies whether the document is opened read-only. 
      /// "FilterName" specifies the component type to create and the filter to use, for example: 
      /// "Text - CSV". For more information see ::com::sun::star::document::MediaDescriptor.
      /// </param>
      /// <returns>
      /// Returns a ::com::sun::star::lang::XComponent for successfully loaded documents or NULL if it failed .
      /// This interface is a generic one and can be used to start further requests on loaded document or control the 
      /// lifetime of it (means dispose() it after using). The real document service behind this interface can be one of follow three ones: 
      /// ::com::sun::star::awt::XWindow for simple components Should be used for viewable components only. 
      /// It is not allowed to dispose it after use directly, because the frame containing the component is its owner. 
      /// Because the frame object is not accessible through the interface too, only an interacting user can do this by closing the frames' window. 
      /// XController for richer components Should be used for real editable components which doesn't need a model. 
      /// It is not allowed to dispose it after use directly, because the frame containing the component is its owner. 
      /// Here the object can be disposed by disposing the frame, that the XController::getFrame() method of the controller returns. 
      /// But for visible components the controller should be asked for permission by calling XController::suspend() before. 
      /// XModel for full featured components
      /// A model that in general can be shared between several view/controller pairs, does not have an explicit owner. 
      /// Every view and also the component that loaded the document may consider itself as an owner. Simply calling XComponent::dispose 
      /// on this model may cause problems, if some members of the "owner community" are currently busy working on the model. 
      /// These problems are handled by explicit closing negotiations through the interface ::com::sun::star::util::XCloseable. 
      /// Direct dispose of the model is allowed only, if this special interface doesn't exist.
      /// </returns>
      T LoadComponentFromFileWithArgs<T>(string fileName, string targetFrameName = "_blank", FrameSearchFlag searchFlags = FrameSearchFlag.AUTO, object[] arguments = null) where T : Component, new();
   }
}
